home *** CD-ROM | disk | FTP | other *** search
/ Aminet 4 / Aminet 4 - November 1994.iso / aminet / dev / m2 / m2_part1.lha / modula / src / Utility.def < prev   
Text File  |  1994-07-30  |  12KB  |  352 lines
  1. DEFINITION FOR LIBRARY MODULE Utility ;
  2.  
  3. FROM SYSTEM IMPORT ADDRESS, STRING, LONGWORD, LONGSET ;
  4. IMPORT Exec ;
  5.  
  6. CONST
  7.   UTILITYNAME = "utility.library";
  8.  
  9. TYPE
  10.   ClockDataPtr     = POINTER TO ClockData           ;
  11.   HookPtr     = POINTER TO Hook           ;
  12.   TagPtr     = POINTER TO Tag           ;
  13.   NamedObjectPtr = POINTER TO NamedObject      ;
  14.   UtilityBasePtr = POINTER TO UtilityBaseRec   ;
  15.  
  16. TYPE
  17.   ClockData = RECORD
  18.     sec , min , hour , mday , month , year , wday : CARDINAL ;
  19.   END ;
  20.  
  21. (* Useful definition for casting function pointers: *)
  22. (* hook.h_SubEntry := HOOKFUNC(AFunction)        *)
  23.  
  24.   HOOKFUNC = PROCEDURE( ) : LONGINT ;
  25.  
  26.   Hook = RECORD
  27.     h_MinNode  : Exec.MinNode ;
  28.     h_Entry    : HOOKFUNC ;    (* assembler entry point *)
  29.     h_SubEntry : HOOKFUNC ;    (* often HLL entry point *)
  30.     h_Data     : ADDRESS  ;    (* owner specific     *)
  31.   END ;
  32.  
  33. (* Hook calling conventions.
  34.  *
  35.  * The function pointed to by Hook.h_Entry is called with the following
  36.  * parameters:
  37.  *
  38.  *    A0 - pointer to hook data structure itself
  39.  *    A1 - pointer to parameter structure ("message")
  40.  *    A2 - Hook specific address data ("object")
  41.  *
  42.  * Control will be passed to the routine h_Entry.  For many
  43.  * High-Level Languages (HLL), this will be an assembly language
  44.  * stub which pushes registers on the stack, does other setup,
  45.  * and then calls the function at h_SubEntry.
  46.  *
  47.  * The standard C receiving code is:
  48.  *
  49.  *  C:HookFunc(struct Hook *hook, APTR object, APTR message)
  50.  * M2:HookFunc( hook : HookPtr ; object : ADDRESS ; message : ADDRESS ) ;
  51.  *
  52.  * Note that register natural order differs from this convention for C/M2
  53.  * parameter order, which is A0,A2,A1.
  54.  *
  55.  * The assembly language stub for "vanilla" C/M2 parameter conventions
  56.  * could be:
  57.  *
  58.  * _hookEntry:
  59.  *    move.l    a1,-(sp)        ; push message packet pointer
  60.  *    move.l    a2,-(sp)        ; push object pointer
  61.  *    move.l    a0,-(sp)        ; push hook pointer
  62.  *    move.l    h_SubEntry(a0),a0    ; fetch C/M2 entry point ...
  63.  *    jsr    (a0)            ; ... and call it
  64.  *    lea    12(sp),sp        ; fix stack
  65.  *    rts
  66.  *
  67.  * With this function as your interface stub, you can write a Hook setup
  68.  * function as:
  69.  *
  70.  * PROCEDURE InitHook( hook: HookPtr ; m2_func: HookFunc ; userdata: ADDRESS );
  71.  * BEGIN
  72.  *   hook^.h_Entry    := hookEntry ;
  73.  *   hook^.h_SubEntry := m2_func   ;
  74.  *   hook^.h_Data     := userdata  ;
  75.  * END InitHook ;
  76.  *
  77.  *)
  78.  
  79. (* Tags are a general mechanism of extensible data arrays for parameter         *)
  80. (* specification and property inquiry. In practice, tags are used in arrays, *)
  81. (* or chain of arrays.                                 *)
  82.  
  83. TYPE
  84.   Tag = LONGINT ;
  85.   TagArrayPtr = POINTER TO ARRAY OF Tag ;
  86.  
  87.   TagItem = RECORD
  88.     ti_Tag : Tag ; (* identifies the type of data *)
  89.     CASE :INTEGER OF
  90.     |1: ti_Any  : LONGWORD ;
  91.     |2: ti_Data : LONGINT  ; (* type-specific data *)
  92.     |3: ti_Set  : LONGSET  ;
  93.     |4: ti_Adr  : ADDRESS  ;
  94.     END ;
  95.   END ;
  96.   TagItemPtr = POINTER TO ARRAY OF TagItem ;
  97.  
  98. CONST
  99. (* constants for Tag.ti_Tag, control tag values *)
  100.   TAG_DONE   = 0 ; (* terminates array of TagItems. ti_Data unused    *)
  101.   TAG_END    = 0 ; (* synonym for TAG_DONE                  *)
  102.   TAG_IGNORE = 1 ; (* ignore this item, not end of array          *)
  103.   TAG_MORE   = 2 ; (* ti_Data is pointer to another array of TagItems *)
  104.            (* note that this tag terminates the current array *)
  105.  
  106.   TAG_SKIP   = 3 ; (* skip this and the next ti_Data items *)
  107.  
  108.   TAG_USER   = LONGINT({31}) ;
  109.  
  110. (* If the TAG_USER bit is set in a tag number, it tells utility.library that  *)
  111. (* the tag is not a control tag (like TAG_DONE, TAG_IGNORE, TAG_MORE) and is  *)
  112. (* instead an application tag. "USER" means a client of utility.library in    *)
  113. (* general, including system code like Intuition or ASL, it has nothing to do *)
  114. (* with user code.                                  *)
  115.  
  116. (*---------------------------------------------------------------------------*)
  117.  
  118. (* Tag filter logic specifiers for use with FilterTagItems() *)
  119.   TAGFILTER_AND = 0 ; (* exclude everything but filter hits    *)
  120.   TAGFILTER_NOT = 1 ; (* exclude only filter hits        *)
  121.  
  122. (*---------------------------------------------------------------------------*)
  123.  
  124. (* Mapping types for use with MapTags() *)
  125.   MAP_REMOVE_NOT_FOUND = 0 ; (* remove tags that aren't in mapList *)
  126.   MAP_KEEP_NOT_FOUND   = 1 ; (* keep tags that aren't in mapList   *)
  127.  
  128. (*---------------------------------------------------------------------------*)
  129.  
  130. (* The named object structure *)
  131. TYPE
  132.   NamedObject = RECORD
  133.     no_Object : ADDRESS ; (* Your pointer, for whatever you want *)
  134.   END ;
  135.  
  136. (* Tags for AllocNamedObject() *)
  137. CONST
  138.   ANO_NameSpace    = 4000 ; (* Tag to define namespace    *)
  139.   ANO_UserSpace    = 4001 ; (* tag to define userspace    *)
  140.   ANO_Priority    = 4002 ; (* tag to define priority    *)
  141.   ANO_Flags    = 4003 ; (* tag to define flags        *)
  142.  
  143. (* Flags for tag ANO_Flags *)
  144.   NSB_NODUPS = 0 ;
  145.   NSB_CASE   = 1 ;
  146.  
  147.   NSF_NODUPS = {NSB_NODUPS} ; (* Default allow duplicates *)
  148.   NSF_CASE   = {NSB_CASE}   ; (* Default to caseless...   *)
  149.  
  150. TYPE
  151.   PackArrayPtr = POINTER TO ARRAY OF LONGINT ;
  152.  
  153. (* PackTable definition:
  154.  *
  155.  * The PackTable is a simple array of LONGWORDS that are evaluated by
  156.  * PackStructureTags() and UnpackStructureTags().
  157.  *
  158.  * The table contains compressed information such as the tag offset from
  159.  * the base tag. The tag offset has a limited range so the base tag is
  160.  * defined in the first longword.
  161.  *
  162.  * After the first longword, the fields look as follows:
  163.  *
  164.  *    +--------- 1 = signed, 0 = unsigned (for bits, 1=inverted boolean)
  165.  *    |
  166.  *    |  +------ 00 = Pack/Unpack, 10 = Pack, 01 = Unpack, 11 = special
  167.  *    | / \
  168.  *    | | |  +-- 00 = Byte, 01 = Word, 10 = Long, 11 = Bit
  169.  *    | | | / \
  170.  *    | | | | | /----- For bit operations: 1 = TAG_EXISTS is TRUE
  171.  *    | | | | | |
  172.  *    | | | | | | /-------------------- Tag offset from base tag value
  173.  *    | | | | | | |              \
  174.  *    m n n o o p q q q q q q q q q q r r r s s s s s s s s s s s s s
  175.  *                    \   | |              |
  176.  *    Bit offset (for bit operations) ----/ |              |
  177.  *                          \               |
  178.  *    Offset into data structure -----------------------------------/
  179.  *
  180.  * A -1 longword signifies that the next longword will be a new base tag
  181.  *
  182.  * A 0 longword signifies that it is the end of the pack table.
  183.  *
  184.  * What this implies is that there are only 13-bits of address offset
  185.  * and 10 bits for tag offsets from the base tag.  For most uses this
  186.  * should be enough, but when this is not, either multiple pack tables
  187.  * or a pack table with extra base tags would be able to do the trick.
  188.  * The goal here was to make the tables small and yet flexible enough to
  189.  * handle most cases.
  190.  *)
  191.  
  192. CONST
  193.   PSTB_SIGNED = 31 ;
  194.   PSTB_UNPACK = 30 ; (* Note that these are active low... *)
  195.   PSTB_PACK   = 29 ; (* Note that these are active low... *)
  196.   PSTB_EXISTS = 26 ; (* Tag exists bit true flag hack...  *)
  197.  
  198.   PSTF_SIGNED = LONGINT({PSTB_SIGNED}) ;
  199.   PSTF_UNPACK = LONGINT({PSTB_UNPACK}) ;
  200.   PSTF_PACK   = LONGINT({PSTB_PACK})   ;
  201.   PSTF_EXISTS = LONGINT({PSTB_EXISTS}) ;
  202.  
  203. (*----------------------------------------------------------------------------*)
  204.  
  205.   PKCTRL_PACKUNPACK = 000000000H ;
  206.   PKCTRL_PACKONLY   = 040000000H ;
  207.   PKCTRL_UNPACKONLY = 020000000H ;
  208.  
  209.   PKCTRL_BYTE = 080000000H ;
  210.   PKCTRL_WORD = 088000000H ;
  211.   PKCTRL_LONG = 090000000H ;
  212.  
  213.   PKCTRL_UBYTE = 000000000H ;
  214.   PKCTRL_UWORD = 008000000H ;
  215.   PKCTRL_ULONG = 010000000H ;
  216.  
  217.   PKCTRL_BIT      = 018000000H ;
  218.   PKCTRL_FLIPBIT  = 098000000H ;
  219.  
  220. CONST
  221.   SHIFT_16 = 65536 ;
  222.   SHIFT_13 = 8192  ;
  223.  
  224. (* Example: (Ga_Left-GA_Dummy)*SHIFT_16+PKCTRL_UBYTE+OFFSET(Gagdet,Hieght) *)
  225.  
  226.   PACK_NEWOFFSET = -1 ;
  227.   PACK_ENDTABLE     =  0 ;
  228.  
  229. TYPE
  230.   UtilityBaseRec = RECORD (* M2: name clash with library base name *)
  231.     ub_LibNode : Exec.Library  ;
  232.     ub_Language: SHORTCARD ;
  233.     ub_Reserved: SHORTCARD ;
  234.   END ;
  235.  
  236. VAR
  237.   UtilityBase : UtilityBasePtr ;
  238.  
  239. (* HookEntry is an assembler stub (see above comment) it should not be called *)
  240. (* directly, its only use is an assigment to the Hook.h_Entry field           *)
  241.  
  242. PROCEDURE HookEntry( ) : LONGINT ;
  243.  
  244. PROCEDURE FindTagItem( tagVal : Tag ; tagList : TagItemPtr ) : TagItemPtr ;
  245.  
  246. PROCEDURE GetTagData( tagVal     : Tag ;
  247.               defaultVal : LONGINT ;
  248.               tagList    : TagItemPtr ) : LONGINT ;
  249.  
  250. PROCEDURE PackBoolTags( initialFlags : LONGINT ;
  251.                 tagList      : TagItemPtr ;
  252.             boolMap      : TagItemPtr ) ;
  253.  
  254. PROCEDURE NextTagItem( VAR tagListPtr : TagItemPtr ) : TagItemPtr ;
  255.  
  256. PROCEDURE FilterTagChanges( changeList , originalList: TagItemPtr ;
  257.                 apply : LONGINT ) ;
  258.  
  259. PROCEDURE MapTags( tagList , mapList : TagItemPtr ; mapType : LONGINT ) ;
  260. PROCEDURE AllocateTagItems( numTags : LONGINT ) : TagItemPtr ;
  261. PROCEDURE CloneTagItems( tagList : TagItemPtr ) : TagItemPtr ;
  262. PROCEDURE FreeTagItems( tagList : TagItemPtr ) ;
  263. PROCEDURE RefreshTagItemClones( clone , original : TagItemPtr ) ;
  264. PROCEDURE TagInArray( tagValue : Tag ; tagArray : TagArrayPtr ) : BOOLEAN ;
  265.  
  266. PROCEDURE FilterTagItems( tagList     : TagItemPtr ;
  267.               filterArray : TagArrayPtr ;
  268.               logic       : LONGINT ) : LONGINT ;
  269.  
  270. (* Hook functions *)
  271.  
  272. PROCEDURE CallHookPkt( hook : HookPtr ; object , paramPacket : ADDRESS ) ;
  273.  
  274. (* Date functions *)
  275.  
  276. PROCEDURE Amiga2Date( seconds : LONGINT ; VAR result : ClockData ) ;
  277.  
  278. PROCEDURE Date2Amiga( date : ClockDataPtr ) : LONGINT ;
  279. PROCEDURE CheckDate ( date : ClockDataPtr ) : LONGINT ;
  280.  
  281. (* 32 bit integer muliply functions *)
  282.  
  283. PROCEDURE SMult32( arg1 , arg2 : LONGINT ) : LONGINT ;
  284. PROCEDURE UMult32( arg1 , arg2 : LONGINT ) : LONGINT ;
  285.  
  286. (* 32 bit integer division functions. The quotient and the remainder are      *)
  287. (* returned respectively in d0 and d1.                          *)
  288. (* Cast the result to an ARRAY [0..1]OF LONGINT to get the quotient/remainder *)
  289.  
  290. PROCEDURE SDivMod32( dividend, divisor : LONGINT ) : LONGREAL ;
  291. PROCEDURE UDivMod32( dividend, divisor : LONGINT ) : LONGREAL ;
  292.  
  293. (*--- functions in V37 or higher (Release 2.04) ---*)
  294.  
  295. (* International string routines *)
  296.  
  297. PROCEDURE Stricmp ( string1, string2 : STRING ) : LONGINT ;
  298. PROCEDURE Strnicmp( string1, string2 : STRING ; length : LONGINT ) : LONGINT ;
  299.  
  300. PROCEDURE ToUpper( ch : CHAR ) : CHAR ;
  301. PROCEDURE ToLower( ch : CHAR ) : CHAR ;
  302.  
  303. (*--- functions in V39 or higher (Release 3) ---*)
  304.  
  305. (* More tag Item functions *)
  306.  
  307. PROCEDURE ApplyTagChanges( list, changeList : TagItemPtr ) ;
  308.  
  309. (* 64 bit integer muliply functions. The results are 64 bit quantities        *)
  310. (* The result type is not is really LONGREAL, cast the result to the type you *)
  311. (* need.                                      *)
  312.  
  313. PROCEDURE SMult64( arg1, arg2 : LONGINT ) : LONGREAL ;
  314. PROCEDURE UMult64( arg1, arg2 : LONGINT ) : LONGREAL ;
  315.  
  316. (* Structure to Tag and Tag to Structure support routines *)
  317.  
  318. PROCEDURE PackStructureTags( pack      : ADDRESS ;
  319.                  packTable : PackArrayPtr ;
  320.                  tagList   : TagItemPtr ) ;
  321.  
  322. PROCEDURE UnpackStructureTags( pack      : ADDRESS ;
  323.                    packTable : PackArrayPtr ;
  324.                    tagList   : TagItemPtr ) : LONGINT ;
  325.  
  326. (* New, object-oriented NameSpaces *)
  327.  
  328. PROCEDURE AddNamedObject( nameSpace , object : NamedObjectPtr ) ;
  329.  
  330. PROCEDURE AllocNamedObjectA( name    : STRING ;
  331.                  tagList : TagItemPtr ) : NamedObjectPtr ;
  332.  
  333. PROCEDURE AllocNamedObject ( name : STRING ;
  334.                  tag1 : Tag ; .. ) : NamedObjectPtr ;
  335.  
  336. PROCEDURE AttemptRemNamedObject( object : NamedObjectPtr ) : LONGINT ;
  337.  
  338. PROCEDURE FindNamedObject( nameSpace  : NamedObjectPtr ;
  339.                name       : STRING ;
  340.                lastObject : NamedObjectPtr ) : NamedObjectPtr ;
  341.  
  342. PROCEDURE FreeNamedObject( object : NamedObjectPtr );
  343. PROCEDURE NamedObjectName( object : NamedObjectPtr ) : STRING ;
  344. PROCEDURE ReleaseNamedObject( object : NamedObjectPtr ) ;
  345. PROCEDURE RemNamedObject( object : NamedObjectPtr ; message : Exec.MessagePtr );
  346.  
  347. (* Unique ID generator *)
  348.  
  349. PROCEDURE GetUniqueID( ) : LONGINT ;
  350.  
  351. END Utility.
  352.